home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume91 / aplictns / mandel10 / part01 / mandel.doc < prev    next >
Text File  |  1991-02-18  |  14KB  |  370 lines
  1.  
  2. -----------------------------------------------------------------------------
  3.  
  4.     Version history
  5.  
  6.     v0.50   First numbered version. Most bugs I've found are fixed.
  7.     v0.60   Workbench interface added.
  8.     v1.00   First public release.
  9.  
  10. -----------------------------------------------------------------------------
  11.  
  12.     BUGS
  13.  
  14.     -   Not very smart handling of AUTOCRAWL
  15.     -   If invoked with too little memory, 56 bytes will mysteriously
  16.         disappear
  17.     -   Window title bar may get trashed if moved too high
  18.  
  19. -----------------------------------------------------------------------------
  20.  
  21.     Copying licence:
  22.  
  23.     This program is copyright 1990 by Hannu Helminen. However, you may
  24.     freely distribute it provided that this package is left intact and no
  25.     charge is taken. You are also licenced to use parts of the code in your
  26.     programs provided that
  27.  
  28.     1)  New versions are clearly marked as such
  29.     2)  You give credit where credit is due (me)
  30.  
  31.     I will not guarantee anything about this program. It seems quite
  32.     reliable to me, though.
  33.  
  34. -----------------------------------------------------------------------------
  35.  
  36.     Package includes:
  37.  
  38.     mandel          Main proggie
  39.     mandel.doc      This file
  40.     iff.library     Used when saving pictures. Place in libs: directory.
  41.  
  42.     source/gui.asm  Graphical user interface
  43.     source/brot.asm This takes care of the actual drawing
  44.     source/pipe.asm A package of fifo routines, as needed by brot
  45.  
  46.     source/macros.i General macros
  47.     source/mbrot.i  brot-specific include file, including my own structure
  48.     source/iff.i    Needed to use iff.library
  49.  
  50. -----------------------------------------------------------------------------
  51.  
  52.  
  53.  
  54.     OVERVIEW
  55.  
  56.     There are quite a few Mandelbrot programs for Amiga, perhaps to the
  57.     extent that I should have named my program "yamb" instead of "mandel".
  58.     (Yet Another MandelBrot)
  59.  
  60.     I hope though that there are enough reasons to satisfy the existence of
  61.     this program. Namely, it was designed with three goals in mind: first,
  62.     speed. Secondly, speed. And last but not least, speed.
  63.  
  64.     Of course, most Mandelbrot programs draw nice-looking pictures, if only
  65.     you can wait for ten minutes or even more for them to be complete.
  66.     Increase the number of iterations and you will have to wait for hours,
  67.     unless you are one of those lucky guys with a 60-MHz 68040-equipped
  68.     A3000's... The main reason for that slowness is the floating point math
  69.     most programs use.
  70.  
  71.     The first version of this program was quite ugly: coded partly in
  72.     Basic, partly in 68000 machine language, it was a mess of a code. Its
  73.     optimized core used 32-bit fixed point math but was still relatively
  74.     slow. After writing it, I forgot it for years.
  75.  
  76.     Then someone in alt.fractals told about a new algorithm called contour
  77.     crawling that produces fast images of Mandelbrot set. I adopted the
  78.     idea and rewrote the program to use it, this time completely in machine
  79.     language. It turned out to be fast (within minutes); that is because it
  80.     does not need to iterate all pixels. And the drawing was visually
  81.     attractive, so it suits well for interactive use.
  82.  
  83.     After imploying a 16-bit iteration for lower resolutions, I found I had
  84.     written the fastest Mandelbrot program I had ever seen. (Ok, forget
  85.     that little transputer...) I cannot pretend to have seen even all Amiga
  86.     ones, though, so there may already be a faster one. If so, please tell
  87.     me that all this code was in vain.
  88.  
  89.  
  90.  
  91.     USAGE
  92.  
  93.     Start from CLI by typing `mandel', or click the icon in Workbench. The
  94.     program will then immediately begin to draw the Mandelbrot set. Various
  95.     options exists, however, to modify how, where and when the image will
  96.     be drawn. Use CTRL-C to abort a draw in progress, and another CTRL-C to
  97.     abort the program.
  98.  
  99.     From CLI: Enter the options after the command, e.g.
  100.  
  101.         mandel -i1000 -j -sram:Picture
  102.  
  103.     Type `mandel ?' to see a brief summary of the options.
  104.  
  105.     From Workbench: Select mandel icon, select `info' from the `Workbench'
  106.     menu and enter options in the TOOL TYPES array, e.g.
  107.  
  108.         I=100
  109.         FLAGS=j
  110.         SAVE=ram:Picture
  111.  
  112.  
  113.     The options are listed below. # is a shorthand for a number.
  114.  
  115.     CLI     WorkBench
  116.  
  117.     -x#     X=#     These determine the point (z = x + yi) in the complex
  118.     -y#     Y=#     plane you will see right in the center of your monitor.
  119.                     They are in the range -4 to 4.
  120.  
  121.     -m#     M=#     This is a logarithmic quantity that represents the
  122.                     magnification of the image. 2^(-m) determines the
  123.                     distance between two lo-res pixels in complex plane.
  124.                     Default is 6, maximum is 29.
  125.  
  126.     -i#     I=#     Iterations. Self-explanatory? No? The greater the
  127.                     number, the more accurate pictures mandel will draw.
  128.                     For further information, refer to APPENDIX A.
  129.                     The maximum number of iterations is 65535.
  130.  
  131.     -jx#    JX=#    These determine a constant (c = jx + jy i) that is used
  132.     -jy#    JY=#    when iterating a Julia set. Each c will produce a
  133.                     different set. See APPENDIX A. These, too, have a range
  134.                     from -4 to 4.
  135.  
  136.     -sname SAVE=name This determines a filename for saved pictures.
  137.  
  138.                     If mandel is operated interactively (g flag is set),
  139.                     the user can save pictures by pressing CTRL S. The
  140.                     standard filename is `mandel.picture', but can be
  141.                     overridden by this option. If many pictures are saved,
  142.                     a number is added at the end to distinguish the files
  143.                     from each other.
  144.  
  145.                     If mandel is in non-interactive use (x flag is set),
  146.                     this options specifies that the image must be saved
  147.                     upon exit, and determines the name for it. Note: if
  148.                     this option does not exists, no image will be saved.
  149.  
  150.     -l      FLAGS=l Normally mandel determines itself whether it should use
  151.     -h      FLAGS=h 16 or 32 bits of precision, as denoded by (a). There
  152.     -a      FLAGS=a are certain, limited circumstances when you need to set
  153.                     the precision explicitely to 16 (l) or 32 (h) bits. In
  154.                     particular, Julia sets that have a complex structure
  155.                     near origo may produce inaccurate images unless 32 bits
  156.                     are used.
  157.  
  158.     -c      FLAGS=c You can enable (c) or disable (w) the crawling if you
  159.     -w      FLAGS=w wish, default is (p), which means to crawl whenever
  160.     -p      FLAGS=p possible. Currently non-connected Julia sets are not
  161.                     crawled because they *could* produce inaccurate
  162.                     results. Future versions might add more sanity checks
  163.                     to this.
  164.  
  165.     -x      FLAGS=x When the (x) flag is used, the programs exits
  166.     -g      FLAGS=g immediately after the first image is drawn. Default is
  167.                     (g) which means to prompt the user with a
  168.                     requester-like window (See below). The x flag is
  169.                     intented for non-interactive use, for example
  170.                     continuous zooms that are achieved via scripts.
  171.  
  172.     -m      FLAGS=m Whether you want to draw Julia (j) or Mandelbrot (m)
  173.     -j      FLAGS=j sets. See APPENDIX A.
  174.  
  175.  
  176.     NOTE:   In Workbench, if multiple FLAGS are used, they *must* be
  177.             combined in a single FLAGS entry, e.g.
  178.  
  179.                 FLAGS=apgx
  180.  
  181.             In CLI, flags *must not* be combined, so do not try `-apgx'
  182.             instead of `-a -p -g -x'.
  183.  
  184.  
  185.  
  186.     GRAPHICAL USER INTERFACE
  187.  
  188.     When mandel is invoked with the -g option, after the first image is
  189.     drawn, a requester-like window will pop in. A grid will also be
  190.     displayed, indicating the centerpoint and borders of the next image.
  191.     Screen title bar will show coordinates of the mouse position.
  192.  
  193.     You can then set the centerpoint by clicking in the image or entering a
  194.     value in the string gadgets labeled `X' and `Y'. Magnification and
  195.     iterations can be set in the gadgets `M' and `I', respectively.
  196.  
  197.     A new quantity can be set using the `Z' gadget: zooming. As its name
  198.     implies, this determines which portion of the current image will be
  199.     shown in the next one. This is a signed number that will be added to
  200.     magnification, thus set z=0 for 100% zooming, z=1 for 50%, z=-1 for
  201.     200% etc. This can also be set by pressing the right mouse button and
  202.     moving it over the image.
  203.  
  204.     The program draws images in one of three modes: ZOOM, DRAW and RESET.
  205.     ZOOM means zooming to the size shown by the grid. DRAW will take the
  206.     numbers from the requester and draw according to them (used for example
  207.     to redraw the same picture, or to quickly enter a very deep
  208.     magnification level)
  209.  
  210.     As setting zoom in DRAW mode makes as little sense as setting
  211.     magnification in ZOOM mode, these modifications will immediately change
  212.     the draw mode, too. The third mode, RESET, will return the
  213.     magnification and centerpoint to normal. The mode can be changed by
  214.     respective gadgets.
  215.  
  216.     Clicking MAND or JULIA will change the set type to Mandelbrot or Julia.
  217.     The magical constant c for Julia sets (See APPENDIX A) can be set as
  218.     follows: Make sure you are in MAND mode. Then select the point c by
  219.     either clicking on the image or entering it in the X/Y-gadgets. Then
  220.     click JULIA gadget and select whatever centerpoint you wish your image
  221.     to have.
  222.  
  223.     Alas, window close gadget only removes the requester window, screen
  224.     title and grid in order to let you view the image. Normal operation is
  225.     resumed by pressing either mouse button.
  226.  
  227.     Quit the program by double-clicking the QUIT gadget or draw a new set
  228.     by double-clicking either in the image or one of the gadgets ZOOM,
  229.     DRAW, RESET.
  230.  
  231.  
  232.  
  233.     AUTHOR
  234.  
  235.     Hannu "The DM" Helminen
  236.     Perkkio
  237.     85900  REISJARVI
  238.     FINLAND
  239.  
  240.     dm@stekt.oulu.fi (for the next few years, I hope)
  241.  
  242.  
  243.  
  244.     THANKS
  245.  
  246.     Thanks to
  247.  
  248.         T. Saarinen for extensive beta-testing
  249.  
  250.         'LS' Hautamaki for not-so-extensive testing
  251.  
  252.         J.M. Jarre who was in great help during long nights of programming
  253.  
  254.         B. Mandelbrot who invented the set that carries his name
  255.  
  256.  
  257.  
  258.  
  259.  
  260.     APPENDIX A: A mathematical definition of Mandelbrot and Julia sets.
  261.  
  262.  
  263.     A point z = x + y i is said to be in the Mandelbrot set if
  264.              0
  265.  
  266.              2
  267.     z    = z   + c  does not go to  +-oo (infinity) when n -> oo
  268.      n+1    n
  269.                            ____
  270.     where c = z .  ( i = ,/ -1   so  z, c are complex numbers )
  271.                0
  272.  
  273.  
  274.     A point z = x + y i is said to be in the Julia set c if
  275.              0
  276.  
  277.              2
  278.     z    = z   + c does not -> oo when n -> oo
  279.      n+1    n
  280.  
  281.  
  282.     NOTE: There are an infinite number of Julia sets, each corresponding to
  283.     one value of c. c is also related to a point in the Mandelbrot set.
  284.     (originally the Mandelbrot set was the set of c's that will produce a
  285.     *connected* Julia set.) Note also that the Julia set looks similar to
  286.     the surroundings of that point in the Mandelbrot set from which the
  287.     Julia set was derived.
  288.  
  289.     Becausese these calculations would take a considerable amount of time
  290.     with any contemporary computer, they are approximated by a finite
  291.     number of iterations (typically 100 or more). An usual test for a point
  292.     z going to infinity is to test whether or not | z | < 2. And since few
  293.     computers can calculate with complex numbers, we can rewrite the
  294.     equation (z -> z**2 + c) in a C-ish style program using only real
  295.     variables z = x + y i:
  296.  
  297.     i = max_iterations;
  298.  
  299.     while (i > 0 && x**2 + y**2 < 4) {
  300.  
  301.     tmpx = x**2 - y**2 + x0;
  302.     tmpy = 2 x y   + y0;
  303.     x = tmpx;
  304.     y = tmpy;
  305.     i--;
  306.  
  307.     }
  308.  
  309.     if (i=0) inside (); else outside();
  310.  
  311.     If you are a first-time user of any Mandelbrot program, I might suggest
  312.     that you study the edge of the black area, because that is where the
  313.     most interesting parts of the set are. (The coloured areas do not
  314.     actually belong to the set, and the interior is, of course, all
  315.     black...)
  316.  
  317.  
  318.  
  319.     APPENDIX B: The contour crawling method
  320.  
  321.     This method works by finding an edge of an area of uniform color, then
  322.     crawling its way through the edge until starting point is reached. The
  323.     interior is then assumed to be of same color. This is of course true
  324.     for the ideal set, but because the image is sampled to a finite set of
  325.     pixels, errors *may* occur. (Haven't seen one so far, though.)
  326.  
  327.     Non-connected Julia sets must not be crawled in the strict mathematical
  328.     sense. However, most of the time mandel produces correct pictures even
  329.     then. So it is quite safe to use the -c option of mandel.
  330.  
  331.  
  332.  
  333.     APPENDIX C: Compilation
  334.  
  335.     Assuming you have a68k v2.61 or higher and blink, the following
  336.     steps are needed to compile a working executable of mandel:
  337.  
  338.     a68k gui.asm -q500 -iinclude:
  339.     a68k brot.asm -q200 -iinclude:
  340.     a68k pipe.asm -q100
  341.     blink gui.o brot.o pipe.o to mandel lib amiga.lib
  342.  
  343.     where include: is assigned to standard assembly include directory.
  344.  
  345.     NOTE: if you have a68k v2.42, gadget arrow images will not be marked as
  346.     going to CHIP ram. This will give you strange-looking images unless:
  347.  
  348.     0)  You have only CHIP ram (poor chap)
  349.  
  350.     1)  You use FastMemFirst, FixHunk, ATOM etc. kludges
  351.  
  352.     2)  Modify the code: allocate some CHIP-mem and CopyMem() the images
  353.         there. This is a kludge, however.
  354.  
  355.     3)  Get v2.62 somewhere (e.g. disk 314 from Fred Fish's
  356.         wonderful collection.)
  357.  
  358.  
  359.  
  360.     APPENDIX D: How to use brot with your own programs?
  361.  
  362.     Just pass the address of a valid mb-structure in a0 (see mbrot.i),
  363.     `jsr MandelBrot' and `XREF MandelBrot' somewhere in your code and
  364.     (b)link your proggie with brot.o and pipe.o. The RastPort you use
  365.     *must* have valid TmpRas and AreaInfo structures attached to it.
  366.     AreaInfo should carry as many vectors as possible (no more than 6553,
  367.     however, since that seems to be a maximum)
  368.  
  369.  
  370.